Contact Import And Management
This document explains the contact import and management functionality for the bulk messaging application. It covers how contacts are imported from CSV, TXT, and Excel files, how phone numbers are normalized and validated, and how contacts are prepared for mass messaging. It also documents the contact data model, error handling strategies, and best practices for preparing contact files.
Supported capabilities:
Automatic detection and parsing of CSV, TXT, and Excel files
Phone number normalization and validation
Manual number entry with name parsing
Contact preview and clearing
Integration with the WhatsApp messaging pipeline
The contact import and management system spans both the Electron frontend and the Python backend. The Electron app provides the UI and orchestrates file selection and manual input. The Python backend performs robust parsing and validation of contact data.
UI and controls"] IPC["main.js
IPC handlers"] PY["pyodide.js
Pyodide loader"] end subgraph "Python Backend" APP["app.py
Flask API"] EXTRACT["extract_contacts.py
File parsing"] VALID["validate_number.py
Validation"] PARSE["parse_manual_numbers.py
Manual parsing"] end UI --> IPC PY --> PARSE IPC --> APP APP --> EXTRACT APP --> VALID APP --> PARSE
Diagram sources
Section sources
File-based import: CSV, TXT, and Excel files are parsed into a unified contact list with number and optional name fields.
Manual number entry: Users can paste or type numbers with optional names; the system parses and validates them.
Phone number normalization: Removes separators, enforces international format, and validates digit counts.
Contact preview and clearing: Users can review imported contacts and clear the list before sending.
Key behaviors:
Automatic column detection for CSV/Excel by heuristics (keywords like “phone”, “number”, “mobile”, “cell”, “tel” for numbers; “name”, “contact”, “person” for names).
Fallback parsing for malformed CSV/Excel using CSV reader.
TXT parsing supports comma, semicolon, tab, or pipe separators and attempts to detect phone numbers in lines.
Section sources
The contact import pipeline integrates Electron UI, IPC, and Python utilities. The Electron app handles file dialogs and manual input, then either invokes Python via Pyodide (browser-side) or the Flask API (desktop mode).
Diagram sources
File Import System (CSV, TXT, Excel)#
CSV parsing:
Uses pandas to read headers and infer phone/name columns by keyword matching.
Falls back to CSV reader if pandas fails.
Produces contacts with number and optional name; unknown names are auto-assigned.
TXT parsing:
Splits lines by separators and attempts to detect phone numbers via regex.
Supports comma, semicolon, tab, and pipe delimiters.
Excel parsing:
Similar to CSV but uses pandas to read Excel sheets.
Keyword-based column detection and fallback to first/second columns.
Diagram sources
Section sources
Phone Number Normalization and Validation#
Removes separators and spaces, keeps digits and plus sign.
Strips leading zeros when not international.
Adds plus prefix for long numbers without it.
Validates digit count to be between 7 and 15 digits.
Returns normalized number or None if invalid.
Diagram sources
Section sources
Manual Number Entry and Parsing#
Supports newline, comma, and semicolon separated entries.
Optionally pairs a name with a number using colon, dash, or pipe delimiter.
If no delimiter is present, attempts to detect which part is the number.
Applies the same normalization and validation logic.
Diagram sources
Section sources
Electron UI Integration#
Import file button triggers a file dialog and sends the selected path to the backend.
Manual number input area supports pasting multiple entries and adds them to the contact list.
Contact preview shows the first few contacts and a clear-all option.
Pyodide is used to load and run the manual number parser in the browser.
Diagram sources
Section sources
Contact Data Model and Mass Messaging Preparation#
Each contact is represented as an object with:
number: normalized phone number string
name: optional display name or auto-generated label
During mass messaging, the message template is personalized by replacing placeholders with the contact’s name (or a default label if missing).
The application constructs chat identifiers for WhatsApp using the normalized number.
Diagram sources
Section sources
Electron UI depends on:
IPC handlers for file import and manual parsing
Pyodide for running Python scripts in the renderer
Python backend depends on:
Pandas for CSV/Excel parsing
CSV module for fallback parsing
Regex for phone number detection and cleaning
The Flask API exposes endpoints for file uploads and manual number parsing.
Diagram sources
Section sources
CSV/Excel parsing uses pandas for speed and robustness; falls back to CSV reader for resilience.
TXT parsing splits by common delimiters and uses regex to detect phone numbers efficiently.
Manual number parsing supports batch input and avoids repeated UI refreshes until parsing completes.
Consider limiting file sizes and providing progress feedback for large imports.
[No sources needed since this section provides general guidance]
Common issues and resolutions:
Unsupported file type:
Ensure the file extension is CSV, TXT, XLS, or XLSX.
Malformed CSV/Excel:
Verify headers and presence of phone number columns.
Confirm UTF-8 encoding and absence of extra blank rows.
Invalid phone numbers:
Numbers must contain 7–15 digits after normalization.
Avoid including letters or special characters not recognized as separators.
Manual number parsing errors:
Use one of the supported formats: “+1234567890”, “Name: +1234567890”, or “+1234567890 - Name”.
Best practices:
Prepare files with clear column names (e.g., “Phone”, “Mobile”, “Name”) to improve automatic detection.
Use consistent separators within a file (comma, semicolon, or tab).
Keep phone numbers in international format with a leading plus sign when possible.
Section sources
The contact import and management system provides robust support for CSV, TXT, and Excel files, along with manual number entry. Phone numbers are normalized and validated to ensure reliable mass messaging. The Electron UI offers intuitive controls for importing, previewing, and managing contacts, while the Python backend delivers resilient parsing and validation logic.
[No sources needed since this section summarizes without analyzing specific files]
Supported File Formats and Data Layouts#
CSV:
Columns: phone-like and name-like fields detected by keywords.
Example layout:
Phone column: “Phone”, “Mobile”, “Cell”, “Tel”
Name column: “Name”, “Contact”, “Person”
TXT:
One contact per line; supports comma, semicolon, tab, or pipe separators.
Example: “+1234567890,John Doe”
Excel:
Sheet-based; similar to CSV with automatic column detection.
Section sources
Contact Data Structure#
number: normalized phone number string
name: optional display name or auto-generated label
Section sources